\section{Developer's Guide}

The appendix is primarily concerned with issues related to adding
extensions to \bit program, such as adding new formats
and/or adding new editing capabilities. In the first a few subsections,
more detailed internal structure of the \bit program is given and
later subsections give specific instructions on adding new format.
It is recommended that you play with the program before you
attempt to add new capabilities to it.
\subsection{Image Types}
\Bit works internally in RGB space, which is split into
packed pixel representation and color index (CI) representation
depending on the input image. Type conversions between
packed pixel and CI are typically transparant and need no
user interation. Grayscale images can exist either in
packed pixel representation or CI representation. Black \& White
images, however, only exist in CI format.

RGB primaries are currently represented by \verb+unsigned char+
and consequently only 8bits of resolution. However, direct use
of \verb+unsigned char+ is strongly discouraged, instead,
use the new type \verb+pc_t+ for primary color varaibles
and resolution of which can be determined form {\tt PCBITS}
and {\tt PCMAX}.

\subsubsection{TrueColor}
True color images are currently handled by packing 4bytes
in RGBA with A being the alpha channel (unused) with
red being the lowest byte. Again, there is no need to
know exactly how a packed pixel is represented, use
the following two routines (macros) to operate on a
particular truecolor pixel (\verb+rgba_t+ is the packed pixel type):
\begin{verbatim}
extern rgba_t Pack(int red, int green, int blue);
extern void Unpack(rgba_t packed, int *red, int *green, int *blue);
\end{verbatim}

Gray images in packed pixel format have a type of \verb+gray_t+,
which is the same as \verb+rgba_t+ in the sense of packing
and unpacking.

\subsubsection{Colormapped images}
CI based image has the type of \verb+ci_t+ having
{\tt CMAPBITS} and its maximum value is {\tt MAXCML}.
The colormap itself has the type of \verb+C_MAP+, which
is a structure containing some control parameters
and the primary color arrays {\verb+pc_t ct[3][MAXCML]+},
where index 0 is red, 1 is green and 2 is blue.

Grayscale images can be represened by colormap based image
and in that case, the image type should be \verb+mapg_t+.
B\&W images are just sepcial cases of grayscale images
with 2 entries in the colormap.

\subsubsection{Summary of image types}
Following types are defined in \verb+utype.h+ and can be used
anywhere if their definations are included:

\begin{verbatim}
typedef enum {
    T_RGBA,                     /* packed RGBA values            */
    T_GRAY,                     /* packed RGBA grayscale         */
    T_CMAP,                     /* mapped images having ci_t type */
    T_GMAP,                     /* gray scale mapped images       */
    T_BW,                       /* Black & White images          */
    T_RGB,                      /* Internal type  (unused)       */
    T_FLEX                      /* flexible(unknown) types       */
} IMG_TYPE;
\end{verbatim}

All types have the obvious meaning except \verb+T_FLEX+,
which indicates an unknown type, or, in other words,
any type is ok. A global function
is provided to convert between all types:

\verb+extern int image_convert_type(IPTR im, IMG_TYPE newtype);+

\noindent
This function will convert the image, pointed to by \verb+im+,
to the requestd type \verb+newtype+. If conversion is sucsseful,
a positive value or zero will be retuned and otherwise
a negative value will be returned. All errors or reasons
for failure are handled by the conversion routine and there is
no need to call error handling routines by the caller, although
the caller must take appropriate action in case of failure.

Exact type of an image can be checked using the following
macros:
\begin{verbatim}
 IS_RGBA(im)         /* checks if image im is in color,packed pixel */
 IS_MGRAY(im)        /* checks if image im is gray in CI      */
 IS_BW(im)           /* checks if image im is black & white   */
 IS_CI(im)           /* checks if image im is in CI           */
 IS_RGBGRAY(im)      /* checks if image im is gray in packed  */
 IS_CPACK(im)        /* checks if image im is in packed pixel */
 IS_GRAY(im)         /* checks if image im is in packed pixel */
\end{verbatim}

\subsection{Image Structure}
\subsection{Memory Routines}
\subsubsection{The Raster matrix}
the raster matrix is a true 2-D matrix.
\subsection{Error Handling}
\subsubsection{informational messages}
\subsubsection{Error messages}
\subsection{Adding new format}
\subsubsection{Loading}
Only two routines are needed for adding a new format:
\begin{verbatim}
int XXX_desc(IPTR im);
int XXX_load(IPTR im);
\end{verbatim}

the description routine should read (or appears to read) from the 
stream \verb+im->fp+ and fill three fields in the image structure,
i.e., the image width, height and image type 
\verb+im->w, im->h, im->type+

The load routine should fill the raster matrix.

In no case should the reading routine close the stream pointed
to by \verb+im->fp+.

\subsubsection{Writing}
\subsubsection{Progress Report}
\subsubsection{More Remarks}
\subsection{Adding Edit Capabilities}
\subsubsection{Rubber Bands}
\subsubsection{Sub-images}
